home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / sortf237.zip / SORTF.DOC < prev    next >
Text File  |  1991-09-20  |  13KB  |  340 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                            SORTF File Sorting Utility
  11.  
  12.                            Version 2.37 - Sep 20, 1991
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                      Index
  19.                                      -----
  20.  
  21.  
  22.                  Purpose  ................................... 1
  23.                   Format  ................................... 1
  24.                   Remarks  ...................................1
  25.  
  26.                  Options summary  ........................... 2
  27.                  Invoking from Quick Basic................... 3
  28.  
  29.                  Examples  .................................. 4
  30.  
  31.                  Version history  ........................... 5
  32.  
  33.                  Usage restrictions  ........................ 6
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.           Copyright (c) Vernon D. Buerg 1985-90. ALL RIGHTS RESERVED.
  54.  
  55.  
  56. SORTF Command                                             Version 2.37  Page 1
  57. -------------                                             Sep 20, 1991
  58.  
  59. Purpose:   The SORTF program reads record data from a file,  sorts the
  60.            records, and writes the data to another file.
  61.  
  62. Format:
  63.            SORTF [d:][path]fname[.ext] [d:][path]fname[.ext]
  64.                  [/+nnnn[,len]] -or- [/-nnnn,[len]]
  65.                  [/Lnnnn]
  66.                  [/R] [/C] [/Q]
  67.                  [/K] or [/X]
  68.  
  69. Remarks:   Records are read from the input file,  sorted,  and written
  70.            to the output file.
  71.  
  72.            Two types of records may be sorted:
  73.  
  74.            1)  logical  records.   Each  record  ends  with a carriage
  75. |              return and line feed, and  may be up to 8192 characters
  76.                in length.
  77.  
  78.            2)  fixed length  records.  Each record  is of length  L as
  79.                defined  by  the  '/Lnnnn'  parameter.  The records may
  80.                contain any  kind of  data, including  carriage return,
  81.                line feed, and end-of-file without effecting the record
  82. |              length. The maximum record is 8192 bytes.
  83.  
  84.  
  85.            The sort  order is  in ascending  ASCII character sequence.
  86.            You may supply the /R  parameter to reverse the sort  order
  87.            for all fields, or supply /- parameters for each key  field
  88.            to  be  sorted  in  reverse  order.   The  key  fields  are
  89.            processed from  left to  right as  supplied in  the command
  90.            line.
  91.  
  92.            The /C option may be added to cause SORTF to treat the  key
  93.            fields  as  case  insensitive  data.   That  is, lower case
  94.            letters in the key field are treated as upper case letters.
  95.  
  96.            You may  supply up  to sixteen  key offsets  and lengths by
  97.            using the /+ or /- parameter, one for each key position and
  98.            its length.   If /+  and /-  are omitted,  the key is taken
  99.            from the first character position for a length of 11.
  100.  
  101. |          The position 'nnnn' may be a value from one to 8192.
  102.  
  103. |          The key length 'len' may be  a value from 1 to 8192. The /+
  104.            operand  specifies  that  the  specified  key  is sorted in
  105.            ascending order.  The /- specifies desending sort order for
  106.            that key.
  107.  
  108.            Use the /Q option to suppress the display of  informational
  109.            messages.  Error messages can not be suppressed.
  110.  
  111.  
  112. SORTF Command           OPTIONS SUMMARY                   Version 2.37 Page 2
  113. -------------                                             Sep 20, 1991
  114.  
  115.  
  116.            /C  specifies  that  the  keys  are  case  insensitive;  if
  117.                supplied, all lower case  characters in the key  fields
  118.                are  converted  to  upper  case  for  the  purposes  of
  119.                sorting.
  120.  
  121.            /R  sort in  reverse order;  over-rides any  /- options and
  122.                treats them all as /+ options.
  123.  
  124.            /Q  suppress informational messages.
  125.  
  126.  
  127.            /K  creates an output file that consists of sorted key data
  128.                which includes a 5-byte information prefix.
  129.  
  130.            /X  like /K, except that the 5-byte information prefix is
  131.                omitted, and a cr/lf (carriage return and line feed)
  132.                is added to each record.
  133.  
  134.  
  135.            /L  specifies the sorting of fixed length records
  136.  
  137.            /+  defines the location  and length of  a key field  to be
  138.                sorted in ascending order
  139.  
  140.            /-  defines the location  and length of  a key field  to be
  141.                sorted in descending order
  142.  
  143.  
  144.  
  145. SORTF Command           INVOKING FROM QUICK BASIC         Version 2.37  Page 3
  146. -------------                                             Sep 20, 1991
  147.  
  148.  
  149.         To invoke SORTF from a Quick Basic program, you can use either
  150.         the SHELL or CALL statements.  Use of SHELL is straightforward.
  151.  
  152.         Use of CALL requires that you include SORTF.OBJ when you LINK
  153.         your QB program.
  154.  
  155.         You need to make memory available to SORTF from your QB
  156.         program.  For QB version 3 and earlier, you can use the LINK
  157.         '/CP:nnnn' option.  For QB 4 and later, I don't know how you
  158.         release memory.  For BC 7, you can use the SETMEM function.
  159.  
  160.  
  161.         In the QB program : CALL SORTF ("test.fil new.fil /+1,12")
  162.                      -or-   SHELL "sortf test.fil new.fil /+1,12"
  163.  
  164.  
  165.         For CALL:           LINK qbprogram + SORTF /CP:5000;
  166.  
  167.  
  168.         The /CP:5000 option will limit the QB program to 80K plus the
  169.         size of its code, data and stack. Whatever is left can be used
  170.         by CALLed programs. That amount will be about 120K less than
  171.         the DOS available memory.
  172.  
  173.  
  174.         For BC 7, here's an example of using SETMEM to release memory:
  175.  
  176.                 M1&=Setmem(0)                   ' Get heap size
  177.                 M2&=Setmem(-M1&+128000)         ' Release all but 128k
  178.                 Call SORTF (" "+infile$+" "+outfile+" /options")
  179.                 M3&=Setmem(M1&)                 ' Re-allocate all to heap
  180.  
  181.  
  182. SORTF Command                EXAMPLES                     Version 2.37  Page 4
  183. -------------                                             Sep 20, 1991
  184.  
  185.          o  to  sort  a  file  in  descending order with the keys in
  186.            position 10:
  187.  
  188.                 SORTF TEST.DAT TEST.SRT /R/+10
  189.  
  190.          o  to sort the same file using keys with 24 characters:
  191.  
  192.                 SORTF TEST.DAT TEST.SRT /R/+10,24
  193.  
  194.          o  to sort a file of fixed length, binary records; the input
  195.            file contains records of 18 bytes each,  the  key is  two
  196.            bytes  at  position  17  in  each  record  in  descending
  197.            order, and 11 bytes at postion 1 in ascending order:
  198.  
  199.                 SORTF SRTCATS.RND SRTCATS.IND /L18 /-17,2 /+1,12
  200.  
  201.          o  to sort on different keys, but creating an an output file
  202.            with the keys only:
  203.  
  204.                 SORTF TEST.DAT TEST.KEYS /-10,2 /+20,4 /-16,3 /K
  205.  
  206.            Note the use of /-.  It specifies that the first and  third
  207.            keys  are  sorted  in  descending  order, the second key is
  208.            sorted in ascending order.
  209.  
  210.            The format of the keys-only file using /K is:
  211.  
  212.            Offset  Length   Contents
  213.            ------  ------   ------------------------------------------
  214.              0       2      Length of data record excluding CR and LF
  215.              2       3      Offset to record in input file
  216.                              +0  hi-byte of 3-byte address offset
  217.                              +1  low word of address offset
  218.              5       n      Variable key data, depends on key definitions
  219.  
  220.            The format of the keys-only file using /X is:
  221.  
  222.            Offset  Length   Contents
  223.            ------  ------   ------------------------------------------
  224.              0       n      Variable key data, depends on key definitions
  225.              n       2      Carriage return and line feed
  226.  
  227.            In the example above, the variable key data format is:
  228.  
  229.              5       2      Data in records at offset 10
  230.              7       4      Data in records at offset 20